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Store games on a NAS 


Instead of using the internal storage or an external USB key/hard drive to store your userdata (games, 
saves, configuration, etc.), you can use a NAS (Network Attached Storage) instead. 


Recommended watching: Batocera Nation's advanced features volume 4. 


Batocera repeatedly checks for a network connection on boot, and if none is present then 

it will automatically fall back to using internal storage. It is not possible to switch the 

location of your userdata without rebooting. If using NAS on a device which has a switch 

to turn on or off Wi-Fi, keep this fact in mind, as turning off the Wi-Fi will effectively wipe 
A the userdata folder from Batocera's perspective. 


In general, if using Batocera on a portable device it's not recommended to use a local 
NAS for its storage anyway due to the instability of its Wi-Fi. Syncthing offers a much 
more secure method of syncing data between portable devices. 


Syntax 


You will need to replace the sharedevice=INTERNAL line with sharedevice=NETWORK inside 
batocera-boot.conf. This file is on the boot partition of the Batocera system. If on a removable 
drive, you can edit it from any computer as it is in a readable FAT32 file system (don't use Windows 
Notepad). 


You can tell if you have successfully done this as the Storage Device in Main Menu > 
System Settings will be blank! But that could also mean you've entered an invalid 
entry to sharedevice... 


g 


Batocera uses a simpler syntax than standard Linux network mounting. For each network share you'd 
like to attach, add an additional line below sharedevice beginning with sharenetwork_smb#= (for 
most Windows Samba shares) or sharenetwork_nfs# (for most Linux Network File System shares) 
where # is the number of the share from 0-9 (yes, this does mean you're limited to only ten shares 
per type of share, this limit may be changed in the future). Following this, put in the keyword for the 
appropriate directory you want to replace in Batocera (as listed below). 


There are the pre-defined keywords you can use: 


SHARE For the whole user data directory. 
ROMS For the roms directory. 


BIOS For the bios directory. 
SAVES For the saves directory. 
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DECORATIONS|Forcustombezels. SS 
SCREENSHOTS For screenshots taken in game or with batocera- screenshot. 


SOUNDS For sounds (v32 and above). 


You can add any combination of the above (except SHARE as that includes everything) by adding 
additional lines. 


ey If you map only certain directories to your NAS, Batocera will search the internal storage 
for the remaining directories. 


For Samba 


@[IP-address/hostname] : [share-name]/[path/to/directory] : [optionl- 
name ]=[optionl-value], [option2-name]=[option2-value], [etc. ] 


Then add the @ symbol, the IP address/hostname of the device with the share, the : character, the 
name of the share followed by a/, then the path to the directory (using Unix syntax / instead of \), 
another : character and then any additional options required for the share separated by a comma (,) 
(guest shares need only : guest as an option, password protected shares need : username=[ your - 
username] , password=[your-password] ). Syntax: 


sharenetwork_[smb-or-nfs][0-9]=[keyword]@[IP-address/hostname] : [share- 


name]/[path/to/directory] : [optionl-name]=[optionl-value] , [option2- 
name]=[option2-value], [etc. ] 


For NFS 


@[IP-address]:[/absolute/path/to/directory] : [optionl-name]=[option1- 
value], [option2-name]=[option2-value],[etc. ] 


Examples are below. If you don't know the exact address to your share already, check the discover 
network share names section below. 
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Samba/Windows share examples 


Windows shares can use identification or a guest account to connect. 


In the following examples, the Windows CIFS share called Documents has a folder named batocera 
which contains the folder structure of Batocera's userdata directory. The IP address of the Windows 
shared server is 192.168.0.1 in this example. If applicable, you can use the hostname of your NAS 
instead, however this may have issues with particular routers. 


The whole user data directory on the NAS 


sharedevice=NETWORK 
sharenetwork_smb1=SHARE@192.168.0.1:Documents/batocera: guest 


Only the ROMs directory on the NAS 


sharedevice=NETWORK 
sharenetwork_smb1=ROMS@192.168.0.1:Documents/batocera/roms:guest 


Only the ROMs directory on the NAS with CIFS authentication 


sharedevice=NETWORK 
sharenetwork_ smb1=ROMS@192.168.0.1:Documents/batocera/roms : username=john, pas 
sword=wayne 


The ROMs, saves and BIOS directories on the NAS 


sharedevice=NETWORK 
sharenetwork_smb1=ROMS@192.168.0.1:Documents/batocera/roms: guest 
sharenetwork_smb2=SAVES@192.168.0.1:Documents/batocera/saves: guest 


Batocera.linux - Wiki - https://wiki.batocera.org/ 


Last update: 2024/01/29 21:17 store_games_on_a_nashttps://wiki.batocera.org/store_games_on_a_nas 


sharenetwork_ smb3=B1I0S@192.168.0.1:Documents/batocera/bios:guest 
Specific SMB version options 


In several cases, you need to add SMB options, for instance if you NAS requires a specific CIFS 
version: 


sharenetwork_ smb1=ROMS@192.168.0.1:Documents/Batocera/roms: guest, vers=1.0 


CIFS version is needed for several NAS vendors: 


e when using and Orange Livebox as a NAS, or on Synology (tested on a DS418play), you need 
vers=1.0 
e if you use OpenMediaVault 5, you need vers=3.0 


In this kind of setup, make sure that: 


e you provide the exact name your SMB share on the NAS (Documents/Batocera/roms in the 
example above is the path from your NAS export) 

e you have the right user authentication (username=j ohn, password=wayne in the example 
above) and, if you use anonymous guest access, that you have write access enabled, so that 
Batocera can write the updated in the gamelist. xml files, and download scraped metadata 
like thumbnails or video snapshots. 


NFS share examples 


The whole user data directory on the NAS 


sharedevice=NETWORK 
sharenetwork_nfs1=SHARE@192.168.0.1:/mnt/Documents/batocera 


Only the ROMs directory on the NAS, with a specific NFS version 


sharedevice=NETWORK 
sharenetwork_nfs1=ROMS@192.168.0.1:/mnt/Documents/batocera/roms:vers=4 


The ROMs, saves and BIOS directories on the NAS 


sharedevice=NETWORK 
sharenetwork_nfs1=ROMS@192.168.0.1:/mnt/Documents/batocera/roms 
sharenetwork_nfs2=SAVES@192.168.0.1:/mnt/Documents/batocera/saves 
sharenetwork_nfs3=B1I0S@192.168.0.1:/mnt/Documents/batocera/bios 
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Mounting network shares behind a VPN or Tailscale network 
Background 


Mounting a shared folder on a server that requires a VPN or Tailscale connection to be established 
first is troublesome due to the Batocera boot initialization process. While Batocera does provide 
various options for you to execute a custom script throughout the boot process, none of them are 
suitable due to several factors. The setup procedure in the VPN/Tailscale documentation is great for 
setting up things like multiplayer, but too late for mounting Batocera core folders. 


Basic boot process flow: 

1. /boot/boot-custom.sh - At this stage, the system's network has not been initialized yet, therefore a 
VPN or Tailscale connection cannot be established. 

2. /etc/init.d/SO7network - This is where the network is initialized. 

3. /etc/init.d/Sl1share - This is where the /userdata is initialized. 

4. /boot/postshare.sh - Executed right after /userdata initialization completed. By this point it is too 
late, and any attempts to mount a VPN/Tailscale network share will fail because those services 
haven't been initialized yet. 

5. /userdata/system/custom.sh - This script is the suggested place for VPN/Tailscale initialization 
according to the docs, but it's also past the /userdata mounting stage. 


From the above, we can see that the VPN/Tailscale client will need to be initialized somewhere 
between steps 2 and 3. 


Workaround 


There is a sharenetwork_cmd# feature that allows you to craft a custom mounting command, 
however, since it accepts any arbitrary shell command we can repurpose it to initialize our 
VPN/Tailscale client. 


First, setup and test the VPN/Tailscale client according to the docs. Once you have successfully 
confirmed that everything is working, disable custom.sh or comment out the lines relevant to 
VPN/Tailscale. Those clients are going to be initialized elsewhere. 


The final result of my configuration looks something like the below. Note that in my example, | am 
using Tailscale and mounting NFS folders, although this should be adaptable for any combination of 
VPN/Tailscale and SMB/NFS. Also, in my example, | am incorporating an ARM-build fix where the 
/dev/net folder needs to be created in addition to a “sleep 2s” command because | have observed 
that the Tailscale daemon sometimes does not finish initializing before the Tailscale client asks it to 
bring up the network. Adjust these items according to your setup. 


sharedevice=NETWORK 

Sharenetwork cmdi=eval if [ ! -d /dev/net ]; then mkdir -p /dev/net; mknod 
/dev/net/tun c 10 200; chmod 600 /dev/net/tun; fi & 
/userdata/tailscale/tailscaled -state /userdata/tailscale/state > 
/userdata/tailscale/tailscaled.log 2>&1 & sleep 2s; 
/userdata/tailscale/tailscale up --accept-routes 

sharenetwork_ nfs1=ROMS@100.0.0.1:/mnt/Documents/batocera/roms 
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sharenetwork_ nfs2=SAVES@100.0.0.1:/mnt/Documents/batocera/saves 
sharenetwork nfs3=BI0S@100.0.0.1:/mnt/Documents/batocera/bios 


Advanced 


Troubleshooting 


Make sure you escape special characters in your CIFS passwords if you have some. To escape a 
character, put a \ in front of it. To escape a \ itself, use \\. 


For troubleshooting purposes, you have /tmp/mountNetwork. log and /tmp/mountNetwork.err 
that will give you some insights on the mount failures if needed. 


Discover network share names 


If you haven't yet used the network share with other devices and aren't confident of the name of the 
share itself (very common for NASes to report a false path to go to to access their data) then you can 
“see” the available network shares from Batocera's file manager. On the system list, press [F1] to 
open it. Then, in the menu at the top of the screen, navigate to Go > Network. The names of the 
available network shares (along with Batocera's own network share) will be shown: 


File Edit View Bookmarks Go Tools Help 


R g v ®©) network:/// 

Places v | MS Batocera (File Sharing) 
cl Applications Ta BATOCERA (Remote Login) 
~~) Share 


=, RASPBERRYPI 


Bios 
P> Rome a solus 
PA screenshots Sh windows Network 


NO_LABEL 


SHARE 
WD-1TB 


proc & 


This can be used to confirm that your Batocera machine can at least see the NAS. You may want to 
note down these names. You will not be able to access any shares from this menu, however. 
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Discover network share paths 


Kodi can be used to see and access network shares. You may need your network share's name in 
order to do this. Open Kodi, then navigate to Files (a.k.a. Enter files section) > Files > Add 
media... (by default, Add videos...) > Browse > Add network location.... 


Movies 


TV shows 
Drary currently en pty. In order to populate it with your persor al media, ente 
f poj 


s" section, add a media source and configure it. After the source has been added < 


ndexed you will be able to browse your library 


Enter files section femove this main menu item 


Radio 


Games 


Add-ons 


Videos 


Sort by: Name 


<} Option 
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Add video source 


Ente 


Browse 


Cancel 


Browse for new share 


base 

Home folder 

Network File System (NFS) 
Root filesystern 

Video playlists 

Windows netwo: 

Zeroconf 


Add networ 


From here, enter the network share name (and your username and password if you don't have 
guest/anonymous access enabled on your NAS): 
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Windows network (SMB) un 


Cancel 


Shared folder 


Username 


Password 


In the case that you don't know the name of the networked device (or one isn't available 
because your router has hostnames disabled/a very strict firewall) it is still possible to 
discover the IP address of the networked device from here. 


Q Instead of going to Add network location..., instead go to Zeroconf browser. You will 
be shown a list of all devices. Select the one you wish to use, and if a 
username/password is required you will be prompted for one. After that, continue 
following the steps as usual, replacing the share name with the IP address you will be 
shown. 


Your share will be added to the list of browseable devices, navigate to it (in this example, 
smb: //RASPBERRYPT) and then navigate to the folder you intend to use for Batocera. 
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Browse for new share 


OK 
base Cancel 
Home fold 
Network File System (NFS) 


Root filesyster nN 


mb://RASPBERRYPI 


Add network location... 


Browse for new share 
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Browse for new share 


OK 


Cancel 


Note down the file path stated at the bottom of the window, this is the path that should be used when 
configuring your NAS. eg. Kodi's path smb: //RASPBERRYPI/samsungltb/Emulation/roms 
contains the share using the Samba (smb) protocol with the hostname RASPBERRYPI with the share 
name samsung1tb and the path being samsung1tb/Emulation/roms. The correct configuration 
lines for batocera-boot. conf would be: 


sharedevice=NETWORK 
sharenetwork_smb1=ROMS@RASPBERRYPI:samsung1ltb/Emulation/roms 


Samba/Windows manually mounted shares 


It is possible to map individual folders with sharenetwork_cmd# if you are familiar with 
. Examples of mapping other directories via sharenetwork_cmd: 


sharenetwork cmdl=mount.cifs -o guest //192.168.0.1/Documents/batocera/music 
/userdata/music 

sharenetwork cmd2=mount.cifs -o guest 
//192.168.0.1/Documents/batocera/cheats /userdata/cheats 

sSharenetwork cmd3=mount.cifs -o guest 
//192.168.0.1/Documents/batocera/screenshots /userdata/screenshots 
sSharenetwork cmd4=mount.cifs -o guest 
//192.168.0.1/Documents/batocera/themes /userdata/themes 


This will only work if sharedevice=NETWORK. You can also use this to just mount anything with 
acceptable bash commands, including folders from local drives, etc. 


Q These will appear as if though they are local to the drive, so keep that in mind when 
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Q troubleshooting in the future! 


NFS and root permissions 


Batocera has a unique root user, so all files accessed on the share are from the root user, which 
can conflict with how other NFS clients access files. You should check how the file permissions are 
declared on your NFS server. A common way to make sure your file permissions are managed 
correctly is to map the file rights to the UID of the user that will access these files locally. Typically, if 
your NFS shares are defined in /etc/exports and you want to give access to a user with UID/GID of 
1000, you can make it with: 


/media/games/batocera 
192.168.0.1(rw,sync,all_squash,anonuid=1000,anongid=1000,no subtree check) 


Troubleshooting 


Logs for share mounting specifically can be found at /tmp/mountDevicesOrNetwork.err after 
booting. If a network share is failing to be booted, Batocera will retry the connection a few times 
before falling back on internal storage. 
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